Boomi API Gateway installation - Windows

Perform the following tasks to complete the Boomi API Gateway installation on Windows.

Verify that your computer meets the Gateway system requirements.
Ensure you meet all Prerequisites.
Download the Gateway installer.
Set up a Windows shared directory for the Gateway.
Install the local Gateway on Windows.
Set up the Gateway's Windows service.
Install additional Gateway nodes. You must complete this task on each Windows machine that you add to the Gateway.
Validate the Gateway installation.

note

Refer to the Gateway maintenance section if you need to adjust how the Gateway runs, change its default settings, or remove it.

tip

If you did not enable local storage during installation, it is recommended that you enable it to reduce unnecessary network traffic.

Prerequisites

To complete the installation, meet the following prerequisites:

Install Powershell.

The API Gateway requires Powershell version 2.0 to be installed. Powershell 2.0 is included in Windows 7 and Windows 2008. If you are installing Powershell on an older version of Windows, install Version 2.0.
Synchronize clocks and timezones.

Ensure that the Gateway’s server clock, including central storage services (e.g., NFS), is synchronized regularly using something like NTP. If the clocks on the machines are not closely synchronized, you are likely to encounter problems with: the clustering protocol, accurate time recording for cross-node actions, and accurate handling of files on the shared file system.

Ensure that all machines are set to use the same time zone. This includes the machines on which the Gateway runs, as well as file servers being used. See your operating system's documentation for instructions on how to set your machines' time zone.
Consider failover and disaster recovery needs.

If you have a multi-node Gateway behind a load balancer for which health checks are configured, in the event the head node fails, failover occurs automatically. The load balancer detects the failure and routes requests for both the Gateway and the Developer Portal to the other node(s). If the Gateway is local and uses an HTTP proxy to connect to the Internet, the proxy continues to work.

For information about backup and disaster recovery best practices for Gateways, review Best Practices for Run Time High Availability and Disaster Recovery Boomi Community article.
Obtain Administrator access.

Depending on the version of Windows you are running, you might require Administrator access to the system where you plan to install the Gateway.

Setting up a Windows shared directory for a Gateway

note

Use Windows file sharing to grant specific users access to the Gateway installation folder path.

Perform the following steps:

Choose or create a user that will be used to run the Gateway.

This user will be used to share the directory as well as to run the Gateway as a service on the various Windows machines.
Create an empty directory on the Windows server.

The Gateway installer uses uniform naming convention (UNC) paths to access a shared directory. Therefore, you should create this directory on a file server that can share it to the other machines that will be used for the Gateway.
Share the directory by using Windows file sharing.

Do not use a mapped network drive path (such as D:\) because you cannot use drive mappings for Windows services. Instead, use a UNC path (such as \\somepath) to the network drive.
Make sure the user has Full Control privileges on the share and the entire Gateway installation folder path.

note
You should grant privileges to the user explicitly rather than adding the user to an administration group.

Installing a local Gateway on Windows

Install the downloaded Windows version of the local Gateway by running the executable file. Gateways require the Java 11 JDK. The installer will install a private copy of Java 11 for the Gateway to use.

note

The private copy of the JDK is a complete JDK that is placed in your Gateway's jre directory. The private JDK will not interfere with a shared JDK (one that you, not the installer, installed). It is not integrated into browsers and does not write registry entries.

Depending on the version of Windows you are running, you might require Administrator access to run the Gateway installer.

The installer gives you the option to select local directories for storing working data and temporary data. It is recommended that you select local directories. If you do select local directories, you must ensure that these directories exist before you run the installer. The installer does not create the directories for you.

Perform the following procedure to install the Gateway:

After downloading the Gateway installer, run the executable file.
If you see a security verification window, click Yes.

The Gateway Setup Wizard opens.
If the installer cannot find the JRE on your machine, you are prompted to download it.
On the Welcome page, click Next.
On the User Information page:
1. Select User Name and Password or Token, depending on how you want to authenticate the Gateway.
2. Enter one of the following, depending on the option you selected:
- your Boomi Enterprise Platform user name and password
- a valid installer token
  
  Installer tokens can be generated when the Gateway installer is downloaded from the Gateway Setup dialog. A token is valid only for the account in which it was generated. Tokens expire after a set amount of time ranging from 30 minutes to 24 hours.
1. Enter a name for the Gateway.
  
  This is the Gateway name that you see when you go to Configure Server > API Gateways. The name defaults to the local host name, but you can change it to something more familiar.
  
  note
  The following characters are reserved and cannot be used in the name: asterisk (*), backslash (\), caret (^), colon (:), dollar sign ($), greater than (>), less than (<), percent (%), pipe (|), question mark (?), quotation mark ("), slash mark (/), Yen sign (¥).
2. If the local machine uses an HTTP proxy to connect to the Internet, select the Use Proxy Settings check box and enter the appropriate host, port, user name, and password for the proxy.
  
  If you do not fill out the proxy settings now, you can add them later.
3. Click Next.
  
  You connect to Boomi Enterprise Platform and your credentials are authenticated.
  
  If you specified a user name and password, the Accounts page is displayed.
  
  If you specified an installer token, the Select Destination Directory page is displayed and you can skip to step 7.
Optional: On the Accounts page:
1. If your user name has access to multiple accounts, you see a list of accounts. Select the account to which this Gateway is associated. This step typically applies only to partners.
2. Click Next.
On the Select Destination Directory page, select the installation directory and click Next.

You must install the Gateway in the shared directory from the first machine. The directory name should look like this: //<host\_name\>/Share/<gateway\_installation\_directory\>.
On the Select Local and Local Temp Directories page:
1. Select a local directory for storing the Gateway node’s working data.
The directory that you select is stored in the Gateway’s Working Data Local Storage Directory property.
1. Select a directory for storing the Gateway node’s temporary data.
The directory that you select appears in the node’s bin/*.vmoptions file as -Djava.io.tmpdir=<your_selected_directory>. If you do not set the local temporary directory, your default Java temp directory is used. The default directory is not recorded in the node’s bin/*.vmoptions file.
1. Click Next.
On the Select Start Menu Folder page, modify any Start Menu settings and shortcuts and click Next.
On the Information page, review the installation settings and click Next.

The installer installs all of the necessary files for your Gateway.
When the installation is complete, click Finish to start the Gateway.

The Gateway runs as a Windows service. You can view the Gateway online by going to Configure Server > API Gateways.

Setting up the Gateway's Windows service

Set up the Gateway’s Windows service through the Administrative Tools on your machine’s Control Panel.

After installing the Gateway, go to Control Panel > Administrative Tools > Services.
Right-click the Gateway service and select Properties.
Click the Log On tab. By default the service will log on as "Local System Account".
Change the service to log on as an account that has access to the shared directory.
Optional: If the user is a service user and not a local administrator of the machine, then you need to grant the user permission to start and stop the service. See the following articles on Windows Service Security:

http://support.microsoft.com/kb/914392

http://technet.microsoft.com/en-us/library/cc742133%28WS.10%29.aspx

http://technet.microsoft.com/en-us/library/cc742037%28WS.10%29.aspx
Get the SID of the Windows user you want to grant access to; typically this is in the form of: S-1-5-21-XXXX-XXXX-XXXX-XXXX
Get the Service DACL of the Gateway service on a particular machine. Run the following command, replacing "Gateway Service Name" with the name of the service that was installed on your machine: sc sdshow "Gateway Service Name" This will return a long Service DACL string like this. (This is only an example.)
```
D:(A;;CCLCSWRPWPDTLOCRRC;;;SY)(A;;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;BA)(A;;CCLCSWLOCRRC;;;IU)(A;;CCLCSWLOCRRCWP;;;SU)(A;;CR;;;AU)(A;;CCLCSWRPWPDTLOCRRC;;;PU)S:(AU;FA;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;WD)
```
Add the following string to the DACL using the SID. Insert this before the S: at the end of the DACL: (A;;CCLCRPWPRC;;; S-1-5-21-XXXX-XXXX-XXXX-XXXX) This will grant Stop/Starting capabilities to this specific user on this specific machine. The new DACL will look like this. (This is only an example.)
```
D:(A;;CCLCSWRPWPDTLOCRRC;;;SY)(A;;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;BA)(A;;CCLCSWLOCRRC;;;IU)(A;;CCLCSWLOCRRCWP;;;SU)(A;;CR;;;AU)(A;;CCLCSWRPWPDTLOCRRC;;;PU)(A;;CCLCRPWPRC;;;
S-1-5-21-XXXX-XXXX-XXXX-XXXX)S:(AU;FA;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;WD)
```

To set the new DACL run the following command, making sure to replace the appropriate variables. Use the DACL from your machine, not the one provided here. Remember to remove newlines.

sc sdset "Gateway Service Name"
"D:(A;;CCLCSWRPWPDTLOCRRC;;;SY)(A;;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;BA)(A;;CCLCSWLOCRRC;;;IU)(A;;CCLCSWLOCRRCWP;;;SU)(A;;CR;;;AU)(A;;CCLCSWRPWPDTLOCRRC;;;PU)(A;;CCLCRPWPRC;;;
S-1-5-21-XXXX-XXXX-XXXX-XXXX)S:(AU;FA;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;WD)"

Start the service.

You can view the Gateway online by going to Configure Server > API Gateways.

Installing additional Gateway nodes on Windows

Install additional Gateways using a Powershell command window to navigate to the bin directory, set the Execution Policy to be unrestricted, and execute the node-install.psl file. These steps must be executed on each machine (node) that will be added to the Gateway.

Run a Powershell command window.
On the machine on which you want to run the node, navigate to the bin directory of the full UNC path of the Gateway, e.g., cd //<host\_name\>/Share/<gateway\_installation\_directory\>/bin.
Temporarily set the Execution Policy for Powershell to be unrestricted for this session.
In the Powershell window, execute the following: set-ExecutionPolicy Unrestricted
Execute the node-install.ps1 file using the following: ./node-install.ps1
Go to Control Panel > Administrative Tools > Services.
Right-click the Gateway service that was created and select Properties.
Click the Log On tab. Change the service to log on as the user that you created for the Gateway.
If the user is a Service User and not a Local Administrator of the machine, then you need to change the Service DACL as described in the instructions for installing the initial Gateway.
Start the service.

After the new node is started, verify that it has joined the Gateway by looking in the <gateway\_installation\_directory/logs/<date\>.container.<machine\_IP\_address\>.log file for a message like:

INFO: Started <machine_IP_address> as CloudletAddress <machine_IP_address>:7800, initial cluster view: CloudletAddress <other_machine_IP_address:7800, CloudletAddress <machine_IP_address>:7800, ...

Validating the Gateway installation

Validate the Gateway installation using the link http://<gateway_node_name:<port_the_gateway_is_using>/_admin/status.

When the validation is successful, you receive the response shown below:

{
  "sync-manager" : {
    "healthy" : true
  },
  "rate-limit" : {
    "healthy" : true
  },
  "management" : {
    "healthy" : true
  },
  "gateway" : {
    "healthy" : true
  }
}